---
title: Troubleshooting
description: Guide for troubleshooting common Pothos issues
---

Common problems and troubleshooting steps.

This document is currently very incomplete, if you run into issues and find a useful solution,
please feel free to add any tips here

## Type issues

1. Ensure that typescript is using `strict` mode

2. Move your builder types to a separate named interface
   - This will make many type errors significantly more readable

```typescript
interface PothosTypes {
  Context: {
    user: {
      id: string;
    };
  };
}

const builder = new SchemaBuilder<PothosTypes>({...});
```

## Slow vscode or typescript performance

1. Ensure you are not including any very complex objects in your `Context` type. See
   [https://github.com/microsoft/TypeScript/issues/45405](https://github.com/microsoft/TypeScript/issues/45405)

## Runtime issues

### Plugin methods are not defined

Ensure that there is only 1 version of each pothos package, and that they are both in the same root
node_modules directly. Pothos plugins import classes from `@pothos/core` to add plugin specific
methods to the class prototypes

### Recieved multiple implementations for plugin

By default, Pothos doesn't allow multiple plugin registrations with the same name. During
development, it can be helpful to disable this check by setting
`SchemaBuilder.allowPluginReRegistration = true`.

Keep in mind that this not only allows plugins to be updated when for example, using HMR but can
also lead to unexpected behavior with plugins using the same name.

### Refs is undefined

If you are running into issues with refs being undefined, it may be due to a circular import. Most
circular imports will work correctly with pothos as long as the following conditions are true:

1. The `builder` is defined in a file that does not import any files that use the builder (or
   indirectly import it).
2. `builder.toSchema()` is called in a file that is not imported by any files that use the builder.

This is generally done by having a simple `builder.ts` that initializes the builder to export. This
file can also define some core parts of your schema (the query object, scalers etc). The rest of the
schema can then import the builder from `builder.ts`. A `schema.ts` file can then import all files
that define parts of the schema. `schema.ts` can then call `builder.toSchema()` and export the
result for use by the server.
